.TH TESTME "1" "January 2014" "testme" "User Commands"
.SH NAME
testme \- TestMe -- Utility to run unit tests
.SH SYNOPSIS
.B testme 
    \fB--chdir dir\fR
    \fB--clean\fR
    \fB--clobber\fR
    \fB--compile\fR
    \fB--continue\fR
    \fB--debug\fR
    \fB--depth level\fR
    \fB--ide\fR
    \fB--log logSpec\fR
    \fB--noserver\fR
    \fB--projects\fR
    \fB--quiet\fR
    \fB--rebuild\fR
    \fB--show\fR
    \fB--trace traceSpec\fR
    \fB--version\fR
    \fB--verbose\fR
    \fB--why\fR
    \fB[filters ...]\fR
.SH DESCRIPTION
TestMe is a dynamic unit test runner. It will traverse a directory tree and automatically build required unit tests and run them with output to the console.

.PP
Unit tests are stand-alone programs that have a '.tst' extension after the normal file extension. For example, a C unit test file would be named 'file.c.tst', while an Ejscript unit test file would be named 'file.es.tst' and a shell script test would be named 'file.sh.tst'.

.PP
Test parameters are passed to unit tests as environment strings with a 'TM_' prefix. 
Unit tests emit results to their standard output and are captured by TestMe. 
Unit tests emit results via a 'pass' or 'fail' command depending on the test results.
Unit tests can control the subsequent execution of tests via a 'skip' command and can write output to the TestMe console via
a 'write' command.
Unit tests can define values in the environment for subsequent tests by emitting a 'set' command (see below). 

.PP
TestMe will automatically compile and recompile C unit tests as required. Ejscript unit tests can be run directly without recompilation.

.SH OPERATION 
When TestMe is invoked, testme traverses the current directory tree looking for unit test files. 
At each directory level, it first runs any setup test files that have a '*.set' extension. The purpose of setup files
is to define the environment and configuration for all tests at or below that directory level. 
.PP
Next, TestMe will compile any Ejscript common files with a '*.es.com' extension. The purpose of common files it to define
shared code that will be used by Ejscript unit tests. Common files should wrap all script in a 'module' directive of the 
same name as the file without extensions. For example: 'support.es.com' would use 'module support { /* code */ }'. The 
compiled common file will be placed in a generated 'testme' directory.

.PP
For all C unit tests with a '*.c.tst' extension, TestMe will first create a 'testme' directory with a MakeMe file for
the unit test. It will then use MakeMe to build the unit test into a stand-alone executable.

.PP
When all is ready, TestMe will run all unit tests with a '*.tst' extension. For subdirectories, TestMe will recurse and
run unit tests in those subdirectories. The aggregated environment is passed down to unit tests in subdirectories. 
Note that if a unit tests uses the 'set' command to define a key value in the environment, it will only be passed to 
unit tests at that directory level or below.

.SH TEST ENVIRONMENT
TestMe communicates test parameters to unit tests via the environment.

.RS 5
 TM_INB      -- Set to the local binary directory.
 TM_DEBUG    -- Set if testme invoked with --debug. Run in debug mode.
 TM_DEPTH    -- Set to the test depth instructed via --depth.
 TM_DIR      -- Set to the directory containing the test.
 TM_NOSERVER -- Set if testme invoked with --noserver. Do not run server-side programs.
 TM_OUT      -- Set to the build output configuration directory.
 TM_PHASE    -- Set to 'Setup', 'Finalize' or 'Test'.
 TM_TOP      -- Set to the top directory for the project.
 TM_*        -- All defines in the me.h are converted to TM_ defines.
.RE
.PP

.SH TEST OUTPUT
A unit test should emit results to the standard out. The following commands are supported.

.RS 5
 fail reason ...
 info message ...
 pass 
 set key value
 skip reason ...
 write message ...
.RE
.PP
A 'fail' command will typically terminate a test run unless testme is invoked with --continue.
A 'pass' command will be counted and if no 'fail' commands are emitted by the unit test, the unit test will be PASSED.
An 'info' command will echo information message to the testme output. A 'write' message will write raw messages to the testme
output. A 'set' command will define a key in the environment that is passed to subsequent unit tests. The 'skip' command
will cause all subsequent unit tests in or below the current directory to be skipped.

.SH TESTME UNIT TEST C API
The follow C API is supported for C unit tests.
.RS 5

 bool  ttrue(expression);
 bool  tfalse(expression);
 bool  ttest(cchar *loc, cchar *expression, bool success);
 cchar *tget(cchar *key, cchar *def);
 int   tgetInt(cchar *key, int def);
 void  tinfo(cchar *fmt, ...);
 void  tset(cchar *key, cchar *value);
 void  tskip(bool skip);
 void  twrite(cchar *fmt, ...);
.RE
.PP

.SH OPTIONS
.TP
\fB\--chdir dir\fR
Change to the given directory before running tests.

.TP
\fB\--clean\fR
Clean the contents of all generated 'testme' directories.

.TP
\fB\--clobber\fR
Remove all generated 'testme' directories.

.TP
\fB\--compile\fR
Compile required C unit tests but do not run. Use --rebuild to force a recompile regardless of whether the unit test file has been updated or not.

.TP
\fB\--continue\fR
Continue to run tests despite any previous errors. Normal operation is to stop testing if any tests fail.

.TP
\fB\--debug\fR
Run in debug mode. Sets TM_DEBUG in the environment.

.TP
\fB\--depth level\fR
Set the unit test depth level.

.TP
\fB\--ide\fR
Run the specified test in an IDE debugger. Supported on Mac OSX only.

.TP
\fB\--log logName[:logLevel]\fR
Specify a file to log test messages. TestMe will normally display test output to the console. The --log option will redirect this output to the specified log file. The log level
specifies the desired verbosity of output. Level 0 is the least verbose and level 5 is the most.

.TP
\fB\--noserver\fR
Do not run server side support code. This emits TM_NOSERVER into the environment for unit tests.

\fB\--projects\fR
Generate IDE projects for the specified unit tests. At least one test must be specified by name on the command line.
The IDE projects are generated in the 'testme' directory.

.TP
\fB\--quiet\fR
Run in quiet mode without trace.

.TP
\fB\--rebuild\fR
Force a recompilation of all C unit tests.

.TP
\fB\--show\fR
Show the actual commands executed by TestMe.

.TP
\fB\--trace logName[:logLevel]\fR
Specify a file to trace HTTP requests. The level specifies the desired verbosity of output. 
Level 0 is the least verbose and level 5 is the most.

.TP
\fB\--version\fR
Print the \fBejs\fR command version and exit.

.TP
\fB\--verbose\fR
Run in verbose mode with more trace about TestMe activities.

.TP
\fB\--why\fR
Display why various tests were run or not and why actions were taken.

.PP
.SH "REPORTING BUGS"
Report bugs to dev@embedthis.com.
.SH COPYRIGHT
Copyright \(co Embedthis Software. TestMe and Ejscript are a trademarks of Embedthis Software.
.br
.SH "SEE ALSO"
me pak
